/**
 * \file
 *
 * \brief Internal interrupt handling
 *
 * This file includes macros and helper functions for setting up
 * interrupt handlers for chip-internal interrupts.
 *
 * Copyright (C) 2009 Atmel Corporation. All rights reserved.
 *
 * \page License
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * 3. The name of Atmel may not be used to endorse or promote products derived
 * from this software without specific prior written permission.
 *
 * 4. This software may only be redistributed and used in connection with an
 * Atmel AVR product.
 *
 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 */
#ifndef INTC_H_INCLUDED
#define INTC_H_INCLUDED

#include <arch/intc.h>

/**
 * \defgroup intc_group Internal Interrupt Processing
 *
 * This module includes functionality to help setting up interrupt
 * handlers for internal (on-chip) interrupts. Such interrupts are
 * generated by chip-internal modules and usually have a very direct
 * path to the interrupt handler in order to minimize interrupt latency.
 *
 * There may be minor differences between architectures, but in general,
 * handlers for internal interrupts are set up in two steps:
 *   - Define a function as an interrupt handler, which provides the
 *     necessary build-time linkage to the low-level entry points. This
 *     is done by the INTC_DEFINE_HANDLER() macro.
 *   - Tell the interrupt controller to call the handler when certain
 *     interrupts are triggered. This must be done at run-time; though
 *     it is not always necessary to do any hardware configuration, the
 *     functions should be called on all architectures in order to keep
 *     the interface similar. This is done by calling
 *     intc_setup_handler(), which will evaluate to nothing (not even a
 *     function call) if nothing needs to be done.
 *
 * Interrupt numbers are specified correspond to the vector number on
 * AVR, and the interrupt group number on AVR32. An AVR32-specific
 * function, intc_get_group_requests(), can be used to distinguish
 * between multiple interrupts inside of a group.
 *
 * @{
 */

/**
 * \def INTC_DEFINE_HANDLER
 * \brief Define an interrupt handler for an integrated peripheral.
 *
 * This binds an interrupt handler function to a low-level entry point,
 * which takes care of saving/restoring registers, finding the
 * handler-specific data, and running any code dealing with soft
 * interrupt handling, etc. before returning.
 *
 * \note This is not a function-like macro; it should not be called
 * from within functions. Instead, it should be invoked at the top level
 * right after the definition of the interrupt handler function.
 *
 * \param id The interrupt vector ID
 * \param handler The interrupt handler function
 * \param level The priority level of this interrupt
 */
/**
 * \def intc_set_irq_data
 * \brief Associate a data pointer with an interrupt
 *
 * \param id The interrupt ID
 * \param data Data to be associated with the interrupt
 */
/**
 * \def intc_get_irq_data
 * \brief Get the data pointer associated with an interrupt
 *
 * If the value stored in \a *pdata is NULL, no interrupt handler has
 * been set up for interrupt \a id.
 *
 * \param id The interrupt ID
 * \param pdata Pointer to a variable in which to store the data pointer
 */
/**
 * \def intc_setup_handler
 * \brief Set up an interrupt handler.
 *
 * This function sets up the internal interrupt controller for
 * handling a given interrupt through the specified handler.
 *
 * \note Usually, this is the only reference to the handler function
 * and associated low-level entry code. This means that it is
 * perfectly ok to define handlers for more interrupts than needed --
 * if they aren't actually enabled by calling this function, they will
 * get discarded at link-time when --gc-sections is used.
 *
 * \param id The interrupt number to associate with the handler
 * \param level The priority level for this interrupt
 * \param data Data to be associated with this interrupt
 *
 * \pre A handler for this interrupt has not already been set up.
 */
/**
 * \def intc_remove_handler
 * \brief Remove an interrupt handler.
 *
 * This will remove a registered interrupt handler, making it possible
 * to set up a different one by calling intc_setup_handler().
 *
 * \note This function doesn't actually reprogram the interrupt
 * controller; it just makes it possible to register a different
 * handler for this interrupt later.
 *
 * \param id The interrupt ID to disassociate with the handler
 */

//! @}

#endif /* INTC_H_INCLUDED */
